The Raster Preferences ('rdip') Resource(IM:XP)

Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /

Chapter 6 - Printing Resources / Printing Resources Reference

Resources Used Only in Printer Drivers

The Raster Preferences ('rdip') Resource
The raster preferences ('rdip') resource, of type gxRasterPrefsType, controls the rendering options for a raster driver. This resource is required for all raster printer drivers. Figure 6-23 shows the structure of a raster preferences resource.
Figure 6-23 The raster preferences resource

The raster preferences resource contains a number of values that define how imaging is performed on the device, followed by an array of plane values, each of which defines parameters for a specific color on the printer. For example, if your driver accepts CMYK (cyan, magenta, yellow, and black color specification) data, QuickDraw GX sends it planes for cyan, magenta, yellow, and black. The values in the plane array correspond to the number of times that you need to send raster data to the printer for color printing.
You need to understand how QuickDraw GX represents and uses colors to understand many of the values in this resource. Refer to two chapters in Inside Macintosh: QuickDraw GX Objects: the "View Objects" chapter and the "Colors and Color-Related Objects" chapter.
Options. A collection of option values that you can combine together to specify how rendering occurs on a raster device. Constants for the raster preference options are shown in Table 6-28 on page 6-70.
Horizontal resolution. The horizontal resolution for imaging as a fixed point number.
Vertical resolution. The vertical resolution for imaging as a fixed point number.
Minimum band size. The minimum band size, in pixels.
Maximum band size. The maximum band size, in pixels. A value of 0 indicates that the maximum band size is the whole page.
RAM percentage. The amount of available temporary memory that can be used. The actual amount used is computed by the following calculation:
((Free memory - RAMSlop) * RamPercentage);
The result is then rounded into a multiple of the minimum band size, but is never made larger than the maximum band size.
RAM slop. The amount to subtract from the total available temporary memory before computing the percentage, as shown above.
Imaging depth. The number of pixels per plane for imaging.
Count. The number of entries in the plane array for this resource. This value is filled in at run time and is not part of the resource definition.
Each entry in the plane array is for a specific color. For example, a driver that accepts CMYK data is sent planes for cyan, magenta, yellow, and black. This data may or may not be equivalent to a band on a ribbon, an ink color, or a wax color; however, each plane that you define in this array does represent one pass of data by the device. Each entry in the plane array contains the following data values.

Plane flags. A collection of flag values that you can combine together to specify controls for rendering the plane. Constants for the plane flags are shown in Table 6-29 on page 6-70.
Angle. The apparent direction to use for halftones, in degrees. This is a fixed point value. The chapter "View Objects" in Inside Macintosh: QuickDraw GX Objects describes using halftones.
Frequency. The size of the dot, in cells per inch, to use for halftones. This is a fixed point value. The chapter "View Objects" in Inside Macintosh: QuickDraw GX Objects describes using halftones.
Dither type. The dithering style, or halftone method, to use for this plane. Constants for color-plane dithering types are shown inTable 6-30 on page 6-71. The results of using these values are shown in the discussion of halftones in the chapter "View Objects" in Inside Macintosh: QuickDraw GX Objects.
Tint type. The type of tinting to apply to this plane. Constants for the plane tinting types are shown in Table 6-31 on page 6-71. The use of these values is explained in the chapter "View Objects" in Inside Macintosh: QuickDraw GX Objects.
Dot color space. Which color space the values in this plane use. The constants for color-space values are shown in the chapter "Colors and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
Dot color profile. The color profile to use for the dot color on this plane. The value gxNoProfile (0) indicates that a color profile is not to be used. Any other value specifies the ID of the color matching ('cmat') resource to use. Color profiles are explained in the chapter "Colors and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
If you specify gxNoProfile, no color matching is performed.
Dot color value 1. The first value for defining the dot color for this plane.
Dot color value 2. The second value for defining the dot color for this plane.
Dot color value 3. The third value for defining the dot color for this plane.
Dot color value 4. The fourth value for defining the dot color for this plane.
Background color space. The color space to use for the background color on this plane. The color-space values are shown in chapter "Colors and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
Background color profile. The color profile to use for the dot color on this plane. The value gxNoProfile (0) indicates that a color profile is not to be used. Any other value specifies the ID of the color matching ('cmat') resource to use. Color profiles are explained in the chapter "Colors and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
If you specify gxNoProfile, no color matching is performed.
Background color value 1. The first value for defining the background color for this plane.
Background color value 2. The second value for defining the background color for this plane.
Background color value 3. The third value for defining the background color for this plane.
Background color value 4. The fourth value for defining the background color for this plane.
Tint space. The color space to use for halftoning. Use one of the values shown in the chapter "Colors and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
Plane color space. The color space of the plane (the original data's color space). Color spaces, color sets, and color profiles are described in the chapter "Colors and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
Plane color set. The resource ID of the color set to use for the plane. You can specify the value gxNoSet to indicate no color set.
Plane color profile. The resource ID of the color profile to use for the plane. You can specify the value gxNoProfile to indicate no color profile.

Table 6-28 shows the constants that you can use to specify the option values for the raster preferences resource.
Table 6-28 Raster preference option values
Constant Value Explanation
gxDefaultRaster 0 Uses default options
gxDontResolveTransferModes 0x01 Tells the system to not resolve transfer modes because your 32-bit device can do it faster on its own
gxRenderInReverse 0x02 Traverses the image in reverse order
gxOnePlaneAtATime 0x04 Renders each plane separately
gxSendAllBands 0x08 Sends bands, even if empty (all white)

Table 6-29 shows the constants that you can use to specify the plane flags values for the raster preferences resource.
Table 6-29 Flags used for each plane in the raster preferences resource
Constant Value Explanation
gxDefaultOffscreen 0 Specifies that the default settings are used, which means that the view port's halftone is based on the information in the imaging system data.
gxDontSetHalftone 1 Specifies that the system must not set the view port's halftone. Use this option when you do not want halftones on a device.
gxDotTypeIsDitherLevel 2 Specifies that the system must set the view port's dither level to the value stored in the gxDotType parameter and ignore other halftone information.

Table 6-30 shows the constants that you can use to specify the plane dithering types for the raster preferences resource.
Table 6-30 Plane dithering types
Constant Value
gxRoundDot 1
gxSpiralDot 2
gxSquareDot 3
gxLineDot 4
gxEllipticDot 5
gxTriangleDot 6
gxDispersedDot 7

Table 6-31 shows the constants that you can use to specify the plane tinting types for the raster preferences resource.
Table 6-31 Plane tinting types
Constant Value Explanation
gxLuminanceTint 1 Use the luminance of the color
gxAverageTint 2 Add all the components, then divide by the number of components
gxMixtureTint 3 Find the closest color on the axis between the foreground and background colors
gxComponent1Tint 4 Use the value of the first component of
the color space
gxComponent2Tint 5 Use the value of the second component of the color space
gxComponent3Tint 6 Use the value of the third component of the color space
gxComponent4Tint 7 Use the value of the fourth component of the color space

The ID of the raster preferences resource must be the constant gxRasterPrefsID. Listing 6-21 shows an example of a raster preferences resource for a 144-dpi four-plane color device, the ImageWriter II raster printer.
Listing 6-21 An example of a raster preferences resource
resource gxRasterPrefsType (gxRasterPrefsID, sysHeap, purgeable)
{
   gxDefaultRaster,        /* default options are fine */
   
   0x00900000,0x00900000,  /* 144X144 dpi device */
   16,                     /* min band size is 2 head heights */
   0,                      /* max band size (0 is full page) */
   0x00004000,             /* RAM percentage (25%) */
   100*1024,               /* RAM slop (100K) */
   4,                      /* 4 bit per plane device */
      {
      /* dithering offscreen */
      3,          /* gxDontSetHalftone+gxDotTypeIsDitherLevel */
      
      0x002D0000,          /* angle unused for dithering */
      0x003C0000,          /* freq unused for dithering */
      4,                   /* dithering with a level of 4 */
      gxLuminanceTint,     /* tint space unused for dithering */
      
                        /* dot color is unused for dithering */
      gxRGBSpace, gxNoProfile, 0, 0, 0, 0, 
                        /* background is unused for dithering */
      gxRGBSpace, gxNoProfile, 0xFFFF, 0xFFFF, 0xFFFF, 0,

      gxRGBSpace,       /* halftone space unused for dithering */

      gxIndexedSpace,         /* indexed color space */
      gxPrintingDriverBaseID, /* ID of the color set to use */
      gxPrintingDriverBaseID, /* ID of the color profile to use */
      };
}; 

**Table 6-28 Raster preference option values**
Constant	Value	Explanation
`gxDefaultRaster`	`0`	Uses default options
`gxDontResolveTransferModes`	`0x01`	Tells the system to not resolve transfer modes because your 32-bit device can do it faster on its own
`gxRenderInReverse`	`0x02`	Traverses the image in reverse order
`gxOnePlaneAtATime`	`0x04`	Renders each plane separately
`gxSendAllBands`	`0x08`	Sends bands, even if empty (all white)

**Table 6-29 Flags used for each plane in the raster preferences resource**
Constant	Value	Explanation
`gxDefaultOffscreen`	0	Specifies that the default settings are used, which means that the view port's halftone is based on the information in the imaging system data.
`gxDontSetHalftone`	1	Specifies that the system must not set the view port's halftone. Use this option when you do not want halftones on a device.
`gxDotTypeIsDitherLevel`	2	Specifies that the system must set the view port's dither level to the value stored in the `gxDotType` parameter and ignore other halftone information.

**Table 6-30 Plane dithering types**
Constant	Value
gxRoundDot	1
gxSpiralDot	2
gxSquareDot	3
gxLineDot	4
gxEllipticDot	5
gxTriangleDot	6
gxDispersedDot	7

**Table 6-31 Plane tinting types**
Constant	Value	Explanation
gxLuminanceTint	1	Use the luminance of the color
gxAverageTint	2	Add all the components, then divide by the number of components
gxMixtureTint	3	Find the closest color on the axis between the foreground and background colors
gxComponent1Tint	4	Use the value of the first component of the color space
gxComponent2Tint	5	Use the value of the second component of the color space
gxComponent3Tint	6	Use the value of the third component of the color space
gxComponent4Tint	7	Use the value of the fourth component of the color space